Agent-friendly documentation: .md companions, llms.txt, coding-agent guide (HF-154)#1696
Open
marcin-kordas-hoc wants to merge 15 commits into
Open
Conversation
…cking Used by the prep-flip T2.5 tier to extract the HyperFormula public API surface at a given git ref and compare between develop and PR HEAD to detect breaking API changes (constructor arg additions, removed exports, lint-scope drift).
…int config Add scripts/*.js override to .eslintrc.js enabling node env and disabling TypeScript-specific rules that do not apply to CJS scripts. Auto-fix semicolons (project enforces no-semicolons style), rename lint_scope variable to lintScope (naming-convention), and add missing JSDoc param/returns descriptions.
Five-component design: VuePress md-companions plugin, Copy Markdown button, static setup-coding-agent page, interactive wizard, and llms.txt/robots.txt updates. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Address 5 findings grounded in VuePress core verification: - respect base '/docs/' and DOCS_DEST in all 5 components - compute Copy Markdown URL from $page.path, not window.location - forbid invented install commands; trace to published skill - token-aware container stripping with code-fence fixture test - flag robots.txt root-vs-/docs/ placement for confirmation Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Six tasks: md-companions plugin (C1), Copy Markdown button (C2), setup-coding-agent page (C3), interactive wizard (C4), llms.txt/robots (C5), and config.js integration. Install commands traced to the published handsontable/handsontable-skills repo; code-fence stripping fixture test included. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Install commands traced to handsontable/handsontable-skills; no invented commands. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…mpanions Strip.js regex was limited to tip|warning|danger|details. The ::: example container (live code runner) leaked into companion .md files. Broadened match to \w+ and strip example containers entirely (they are demo markup, not prose). Added 8th assertion to the test fixture. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…p page - require md-companions plugin, register with DOCS_HOSTNAME - globalUIComponents: ['CopyMarkdownButton'] - add 'Set up your coding agent' to Getting started sidebar Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
strip.js: - track full fence marker length (CommonMark); inner ``` no longer closes ```` - bail out verbatim on unclosed ::: container (no silent page truncation) - 9th test assertion for nested fence lengths index.js: - wrap per-page work in try/catch; one bad page warns and continues - substitute real base/hostname in corpus header (was literal <base>) CopyMarkdownButton.vue + CodingAgentWizard.vue: - clipboard fallback via document.execCommand for non-HTTPS contexts - isSecureContext guard + .catch() on Clipboard API promise - null-guard on this.current in wizard copy() setup-coding-agent.md: - relative links to llms-full.txt (../llms-full.txt) to survive any base-path edge cases in static-file link resolution Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
👷 Deploy request for hyperformula-dev-docs pending review.Visit the deploys page to approve it
|
The md-companions markdown stripper is the acceptance gate for the agent-friendly docs (per-page .md companions + llms.txt), but its test lived at docs/.vuepress/plugins/md-companions/strip.test.js — a path and suffix Jest's testMatch (`test/**/*spec.(ts|js)`) never discovers, so it never ran in CI. - Move the assertions into test/docs/md-companions-strip.spec.js as a Jest spec, where the default glob picks them up. The file is `.js`, so Karma's `.spec.ts`-only require.context skips it (the stripper is plain Node code, not part of the browser bundle). - Add an ESLint override for `**/test/**/*.spec.js` mirroring the existing `scripts/*.js` relaxations (node env, allow require of untyped modules). - Remove the orphan strip.test.js. - CHANGELOG: note the agent-friendly docs under [Unreleased] > Added. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
marcin-kordas-hoc
force-pushed
the
feat/hf-154-agent-friendly-docs
branch
from
c7ef315 to
f49d15b
Compare
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit f49d15b. Configure here.
| - [ ] Interactive wizard renders, IDE selection shows verified snippet, copy works | ||
| - [ ] `llms.txt` + `robots.txt` point at `/docs/llms-full.txt` | ||
| - [ ] Code-fence-with-`:::` fixture test passes (no false stripping) | ||
| - [ ] Full `npm run docs:build` succeeds; `npm run lint` exit 0 |
There was a problem hiding this comment.
Internal plans published in docs
Medium Severity
Two internal HF-154 implementation plan/spec markdown files were added under docs/superpowers/. VuePress builds every file under docs/ into the public site, and md-companions includes each page in llms-full.txt, so agent-facing corpus gets internal subagent workflow instructions instead of HyperFormula user documentation.
Additional Locations (1)
Reviewed by Cursor Bugbot for commit f49d15b. Configure here.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context
HF-154 — make the HyperFormula docs friendlier to coding agents and LLMs. On top of the existing VuePress portal this adds:
.mdcompanions — every doc page is also served as clean, VuePress-stripped markdown (amd-companionsVuePress plugin).llms.txt— a top-level index pointing agents at the markdown sources.CopyMarkdownButton.vue) — one-click copy of a page's markdown.docs/guide/setup-coding-agent.md) plus aCodingAgentWizard.vuehelper.context7.jsonand arobots.txtupdate so agent doc-access tooling (Context7 / GitMCP) can discover the sources.The markdown stripper (
md-companions/strip.js) is the fidelity-critical piece: it turns VuePress-flavoured markdown (:::containers,<script>/Vue components,[[toc]], live:::exampledemos, nested code fences) into clean markdown for the.mdcompanions andllms.txt.How did you test your changes?
docs/.vuepress/plugins/md-companions/strip.test.js— a path/suffix Jest'stestMatch(test/**/*spec.(ts|js)) never discovers, so it never ran in CI. It is nowtest/docs/md-companions-strip.spec.js, a.jsJest spec picked up by the default glob (9 assertions, all passing vianpm run test:jest). Being a.jsfile, Karma — which only globs.spec.ts— skips it; the stripper is plain Node code, not part of the browser bundle.**/test/**/*.spec.jsmirroring the existingscripts/*.jsrelaxations (node env,requireof untyped modules), so the new spec lints clean.npm run lintreports no new errors.Types of changes
Related issues:
Checklist:
Note on the Astro migration
The docs-portal Astro migration (#1686) is a separate track. If it lands first it would supersede this VuePress plumbing (the
md-companionsplugin and.vuecomponents are VuePress-specific); the agent-friendly outputs (.mdcompanions,llms.txt, coding-agent guide) would need re-homing in Astro. Flagging so the two tracks can be sequenced.Note
Low Risk
Changes are limited to documentation build, static assets, and dev tooling; the spreadsheet engine and public runtime API are untouched.
Overview
Adds LLM/agent-oriented documentation outputs on top of the existing VuePress site: a post-build
md-companionsplugin writes stripped per-page.mdfiles andllms-full.txt, driven bystripVuePressSyntax(containers, Vue tags, demos, fence-safe).Site UX: global Copy Markdown button copies the page’s
.mdURL; new Set up your coding agent guide withCodingAgentWizard;llms.txt,robots.txtpointer, and rootcontext7.jsonfor discovery tools.Quality/CI: stripper tests move to
test/docs/md-companions-strip.spec.jsfor Jest; ESLint overrides forscripts/*.jsandtest/**/*.spec.js. CHANGELOG updated.Also includes
scripts/extract-public-api.js(public API JSON for cross-ref contract checks) and internal HF-154 plan/spec markdown underdocs/superpowers/— not part of the published docs feature itself.Reviewed by Cursor Bugbot for commit f49d15b. Bugbot is set up for automated code reviews on this repo. Configure here.